Squid Connector¶

The Squid connector receives incoming requests from the Squid forward proxy and forwards them to the engine for processing. The engine processes each request and returns a response to the connector. Communication between the connector and the engine is performed using the proprietary Defendr protocol. Multiple instances of the connector process may be running concurrently; in such cases, multiple TCP sessions will be established between the connectors and the engine.

Configuration File¶

The squid connector can be configured through its configuration file, written in the TOML format. The latter is very similar in structure and readability to the classic .ini files used in Windows environments. No advanced syntax or complex grammar is required: the files consist of simple key-value pairs organized within sections.

The default location for the squid connectors configuration file is /etc/controlguard/sqdconnector.conf.

[global]¶

The global section is designed to define configuration parameters that apply universally across al squid connectors. These parameters typically include essential settings such as the unique identifier, the required data format for Squid requests, and user-configurable timers.

Parameters:

Name	Type	Description	Default
`asn`	string	The connector's Autonomous System Number (ASN)	`64512`
`ip`	string	The connector's identifier dotted decimal notation	`127.0.0.1`
`port`	integer	The engine destination port	`11224`
`request_format`	integer	The request format type	`0`
`retry`	integer	The retry timer interval in milliseconds	`30000`
`timeout`	integer	the timeout timer timeout in milliseconds	`60000`
`dead`	integer	The dead timer interval in milliseconds	`180000`

asn¶

The asn parameter specifies the Autonomous System Number (ASN) of the connector. An ASN is a unique 16-bit integer in the range of 1 to 65534, assigned to identify a distinct administrative entity in the controlguard ecosystem. By default the ASN value is 64512.

ip¶

The ip parameter specifies the IP address that the connector uses for identification purposes. As of this writing, it is used solely for administrative purposes and does not necessarily reflect the actual source IP address from which the connection to the engine is established.

port¶

The port parameter specifies the TCP port to which the connector should connect. By default, the ControlGuard engine listens on TCP port 11224.

request_format¶

The request_format parameter specifies the Squid request format that the connector is configured to handle. It defaults to 0 which is our proprietary extended request format.

retry¶

The retry parameter specifies the retry timer interval in milliseconds. By default, the retry timer is set to 30,000 milliseconds (equivalent to 30 seconds).

timeout¶

The timeout parameter specifies the duration in milliseconds after which an inactive neighbor is considered timed out. When a timeout occurs, a keepalive message is sent to verify that the neighbor is still alive.

dead¶

The dead parameter specifies the time interval in milliseconds after which a session neighbor (the engine) is declared dead if no message or keepalive is received. Upon reaching this timer, the neighbor is marked as dead and scheduled for removal from the internal sessions' states.

[engine]¶

The engine section (or table) defines the engine related parameters. Each subsection (or sub-table) represents a unique engine definition. Typically, in a ControlGuard environment, at least one entry is mandatory to define the remote engine.

Parameters:

Name	Type	Description	Default	Required
`host`	string	The hostname or IP address of the remote engine		Mandatory
`port`	integer	The engine destination port	`11224`	Optional
`key`	string	The shared authentication key		Mandatory

Example:

[engine.host1]
host = "172.16.32.1"
port = 11224
key = "abcdef1234567890" # (1)!

This attribute is mandatory and must be explicitly configured with identical values on both sides of the peer relationship.

The above example defines an engine named host1 listening on IP address 172.16.32.1 and TCP port 11124. The authentication key is configured with a shared secret that is used by both the connector and the engine to ensure that only authenticated peers can establish peer relashionship.

host¶

The host parameter specifies the hostname or IP address of the engine.

port¶

The port parameter specifies the port to connect to. The default service port for ControlGuard Engine is tcp 11224.

key¶

Mandatory Key Attribute

By default, ControlGuard enforces mutual peer authentication between the engine and the connectors. For this reason, the key attribute is mandatory and must be explicitly configured.

The key attribute value set the shared key used for mutual peer authentication. Any string of up to 128 characters may be used; longer strings will be truncated.

[tls]¶

The tls section defines the Transport Layer Security (TLS) parameters used by connectors to establish secure connections to the engine.

Parameters:

Name	Type	Description	Default
`disable`	bool	Disable TLS support	false

disable¶

The disable parameter allows TLS support to be entirely deactivated at the connector level. The connector won't attempt to upgrade connections to TLS and will use clear-text, unsafe communication instead.

Security risks

We strongly recommend against disabling TLS, as doing so leaves all communication between the engine and its peers vulnerable to man-in-the-middle attacks and eavesdropping.

Performance considerations

Disabling TLS may improve performance by reducing the per-request processing overhead associated with encryption. However, this enhancement is achieved at the cost of security.